Add @res.hoistedFunction support for flat JS export - #8402

Summary

Adds @res.hoistedFunction, a compiler-supported attribute for exporting nested module functions through flat JS exports.

A function defined inside an exported module can now be marked as hoisted. The compiler keeps the normal nested module shape, but also emits a root-level alias/export for the function and records that alias in .cmj metadata so downstream modules can import it directly.

Motivation

Nested module functions are normally emitted and consumed through property access:

// Producer.res
module A = {
  module B = {
    let make = () => "ok"
  }
}

// consumer output
Producer.A.B.make()

This is the first step for my take on #8293. That work needs generated JSX code for React Server Components to expose nested component functions through stable flat JS exports:

Producer.A$B$make()

Because producers and consumers are compiled separately, the consumer cannot infer from the source path alone whether Producer.A.B.make also has a flat export. The producer therefore records hoisted paths in .cmj metadata, and consumers use that metadata to emit the flat import when it is available.

Design

Source Marker

The feature introduces:

@res.hoistedFunction
let make = () => ...

The attribute currently applies only to function bindings. If it is placed on a non-function value or an external declaration, the compiler reports a misplaced-attribute warning.

The attribute deliberately applies only to nested module function bindings with a fixed exported path, matching the intended use case. Local functions, functions declared directly at the file root, local modules, and functor bodies cannot form such an export and produce a misplaced-attribute warning.

Producer Output

When an exported module contains a hoisted nested function, the compiler keeps the original module structure and adds a root-level alias.

For a source path like:

A.B.make

the compiler emits a flat export:

A$B$make

The nested function remains available at its normal path, while the flat alias is exported as a separate JS value.

Path Identity and Exotic Identifiers

The flat JavaScript name cannot safely identify the original source path by itself.

Representing a nested path by joining its segments with $ would be ambiguous because ReScript allows escaped identifiers containing $. For example, these are distinct source paths:

A.B.make
A.\"B$make"

However, both have the same natural flat JavaScript spelling:

A$B$make

Encoding the path segments in the generated export name would remove the ambiguity, but it would also produce surprising JavaScript names and prevent exotic identifiers from retaining their intended spelling.

Instead, the implementation separates source-path identity from the generated JavaScript name:

• .cmj metadata stores the exact source path as a list of segments.
• The generated export retains its natural flat JavaScript name.

Consumers therefore look up hoisted exports using the structural source path, while the generated JavaScript remains readable and predictable.

If two hoisted paths produce the same JavaScript export name, or if that name conflicts with an existing top-level binding, compilation fails with a clear error.

.cmj Metadata

The .cmj format stores each hoisted export as:

type hoisted_export = {
  path: string list;
  name: string;
}

For example, A.B.make is represented as:

{
  path: ["A", "B", "make"];
  name: "A$B$make";
}

The path is used for exact source-level lookup. The name is the compiler identifier used for the flat JavaScript export.

This metadata remains separate from the regular values table, which continues to hold arity and cross-module optimization information.

Consumer Lookup

When compiling a cross-module nested read such as:

Producer.A.B.make

normal compilation looks up the first field, A, in the producer’s .cmj and emits the remaining property accesses:

Producer.A.B.make

For a nested read, the compiler now also reconstructs the exact source path and checks the producer’s hoisted export metadata.

If the path is present, it uses the recorded flat export name:

Producer.A$B$make

Otherwise, it falls back to the normal property chain.

Because lookup uses the structural path rather than a $-joined key, exotic identifiers cannot accidentally resolve to another binding’s hoisted export.

Performance

Modules without @res.hoistedFunction require only a shallow, allocation-free scan of their top-level bindings.

For each annotated function, the generated JavaScript contains one additional alias assignment and export. Calls use the flat export directly; there is no runtime path lookup or encoding.

Consumer lookup is compile-time only and scans the dependency’s normally very small list of hoisted exports.

Tests

Adds coverage for:

• several levels of nested modules;
• mutually recursive modules;
• function bindings with explicit type annotations;
• hoisted and non-hoisted functions in the same modules;
• cross-module access through flat exports;
• escaped keyword, operator, and $ identifiers;
• structurally distinct paths with the same flattened spelling;
• collisions between hoisted exports;
• collisions with existing top-level bindings;
• invalid attribute payloads and placements where no flat export can be generated;
• executed runtime behavior of the generated JavaScript.